/**
 * Modal Sheet 组件类型定义
 *
 * 🎯 类型设计理念：
 * 1. 类型安全：完整的 TypeScript 类型覆盖
 * 2. 可扩展性：联合类型支持自定义扩展
 * 3. 向后兼容：新增属性使用可选类型
 * 4. 文档化：每个类型都有详细的注释说明
 *
 * 📋 类型分类：
 * - 基础类型：尺寸、位置、动画等枚举类型
 * - 配置接口：组件 Props 和配置选项
 * - 回调类型：事件处理函数签名
 * - Ref 接口：命令式 API 定义
 * - 上下文类型：Context 状态结构
 *
 * 🔧 设计模式：
 * - 联合类型：支持多种取值的枚举
 * - 可选属性：渐进增强的功能配置
 * - 泛型约束：类型安全的扩展点
 * - 接口继承：复用和扩展基础类型
 */

import type { ReactNode, CSSProperties } from 'react';

/**
 * Modal Sheet 尺寸类型
 */
export type ModalSheetSize = 'small' | 'medium' | 'large' | 'full' | 'auto';

/**
 * Modal Sheet 位置类型
 */
export type ModalSheetPosition = 'bottom' | 'top' | 'left' | 'right';

/**
 * Modal Sheet 动画类型
 */
export type ModalSheetAnimation =
  | 'slide'
  | 'fade'
  | 'scale'
  | 'bounce'
  | 'none';

/**
 * 动画预设类型
 */
export type AnimationPreset =
  | 'smoothSlide'
  | 'springy'
  | 'snappy'
  | 'dramatic'
  | 'staggered'
  | 'custom';

/**
 * Snap Point 类型定义
 * - number: 具体像素值 (如 100 表示 100px)
 * - 0-1 的小数: 百分比 (如 0.5 表示 50%)
 * - 负数: 距离顶部的像素值 (如 -100 表示距顶部 100px)
 * - 0: 关闭状态
 * - 1: 全屏状态
 */
export type SnapPoint = number;

/**
 * Modal Sheet Ref 接口
 */
export interface ModalSheetRef {
  /** 跳转到指定的 snap point */
  snapTo: (index: number) => void;
  /** 获取当前 snap point 索引 */
  getCurrentSnap: () => number;
  /** 关闭 Modal Sheet */
  close: () => void;
  /** 聚焦到弹框元素 */
  focusElement: () => void;
  /** 宣布状态变化给屏幕阅读器 */
  announceChange: (message: string) => void;
}

/**
 * Modal Sheet 主要属性接口
 */
export interface ModalSheetProps {
  /** 是否显示 Modal Sheet */
  open: boolean;

  /** 关闭回调函数 */
  onClose: () => void;

  /** 子元素内容 */
  children: ReactNode;

  /** Snap Points 吸附点数组 */
  snapPoints?: SnapPoint[];

  /** 初始 Snap Point 索引 */
  initialSnap?: number;

  /** Snap Point 变化回调 */
  onSnap?: (snapIndex: number, snapValue: SnapPoint) => void;

  /** Modal Sheet 尺寸 */
  size?: ModalSheetSize;

  /** Modal Sheet 位置 */
  position?: ModalSheetPosition;

  /** 动画类型 */
  animation?: ModalSheetAnimation;

  /** 是否显示遮罩层 */
  showOverlay?: boolean;

  /** 点击遮罩层是否关闭 */
  closeOnOverlayClick?: boolean;

  /** 按 ESC 键是否关闭 */
  closeOnEscape?: boolean;

  /** 是否可拖拽调整大小 */
  resizable?: boolean;

  /** 是否可拖拽移动位置 */
  draggable?: boolean;

  /** 自定义样式类名 */
  className?: string;

  /** 自定义内联样式 */
  style?: CSSProperties;

  /** 遮罩层自定义样式类名 */
  overlayClassName?: string;

  /** 遮罩层自定义内联样式 */
  overlayStyle?: CSSProperties;

  /** 动画持续时间（毫秒） */
  animationDuration?: number;

  /** 动画预设 */
  animationPreset?: AnimationPreset;

  /** 自定义动画配置 */
  customAnimationConfig?: {
    /** 缓动函数 */
    easing?: string | number[] | ((t: number) => number);
    /** 是否启用弹性动画 */
    enableSpring?: boolean;
    /** 弹性动画配置 */
    spring?: {
      stiffness?: number;
      damping?: number;
      mass?: number;
    };
    /** 连锁动画配置 */
    chainAnimation?: {
      enabled?: boolean;
      stagger?: number;
      direction?: 'normal' | 'reverse';
    };
  };

  /** 是否启用动画增强效果 */
  enableAnimationEnhancements?: boolean;

  /** 是否启用主题系统 */
  enableTheme?: boolean;

  /** 自定义主题类名 */
  themeClassName?: string;

  /** z-index 层级 */
  zIndex?: number;

  /** 是否锁定页面滚动 */
  lockScroll?: boolean;

  /** 是否在打开时自动聚焦 */
  autoFocus?: boolean;

  /** 聚焦陷阱：是否将焦点限制在 Modal 内 */
  trapFocus?: boolean;

  /** 自定义容器元素 */
  container?: HTMLElement | (() => HTMLElement);

  /** 打开前回调 */
  onBeforeOpen?: () => void;

  /** 打开后回调 */
  onAfterOpen?: () => void;

  /** 关闭前回调 */
  onBeforeClose?: () => void;

  /** 关闭后回调 */
  onAfterClose?: () => void;

  /** 拖拽开始回调 */
  onDragStart?: (event: MouseEvent | TouchEvent) => void;

  /** 拖拽中回调 */
  onDrag?: (
    event: MouseEvent | TouchEvent,
    position: { x: number; y: number }
  ) => void;

  /** 拖拽结束回调 */
  onDragEnd?: (
    event: MouseEvent | TouchEvent,
    position: { x: number; y: number }
  ) => void;
}

/**
 * Modal Sheet Header 属性接口
 */
export interface ModalSheetHeaderProps {
  /** 标题内容 */
  title?: ReactNode;

  /** 是否显示关闭按钮 */
  showCloseButton?: boolean;

  /** 关闭按钮点击回调 */
  onClose?: () => void;

  /** 自定义样式类名 */
  className?: string;

  /** 自定义内联样式 */
  style?: CSSProperties;

  /** 子元素内容 */
  children?: ReactNode;
}

/**
 * Modal Sheet Body 属性接口
 */
export interface ModalSheetBodyProps {
  /** 自定义样式类名 */
  className?: string;

  /** 自定义内联样式 */
  style?: CSSProperties;

  /** 子元素内容 */
  children: ReactNode;

  /** 是否启用滚动 */
  scrollable?: boolean;
}

/**
 * Modal Sheet Footer 属性接口
 */
export interface ModalSheetFooterProps {
  /** 自定义样式类名 */
  className?: string;

  /** 自定义内联样式 */
  style?: CSSProperties;

  /** 子元素内容 */
  children: ReactNode;

  /** 对齐方式 */
  align?: 'left' | 'center' | 'right' | 'space-between';
}

/**
 * 位置坐标接口
 */
export interface Position {
  x: number;
  y: number;
}

/**
 * 尺寸接口
 */
export interface Size {
  width: number;
  height: number;
}

/**
 * Modal Sheet 上下文接口
 */
export interface ModalSheetContextValue {
  /** 是否打开 */
  isOpen: boolean;

  /** 关闭函数 */
  close: () => void;

  /** 当前尺寸 */
  size: ModalSheetSize;

  /** 当前位置 */
  position: ModalSheetPosition;

  /** 是否可拖拽 */
  draggable: boolean;

  /** 是否可调整大小 */
  resizable: boolean;
}
